Skip to content

docs: add deployment and threading safety guide (closes #48)#63

Merged
wpak-ai merged 1 commit into
masterfrom
fix/no-threading-deployment-safety-doc
May 21, 2026
Merged

docs: add deployment and threading safety guide (closes #48)#63
wpak-ai merged 1 commit into
masterfrom
fix/no-threading-deployment-safety-doc

Conversation

@bradjin8
Copy link
Copy Markdown
Collaborator

@bradjin8 bradjin8 commented May 21, 2026 •
edited by coderabbitai Bot
Loading

Closes #48

Summary

  • Add DEPLOYMENT.md documenting supported WSGI setups (Werkzeug dev server, gunicorn, waitress), concurrency models, and production quick-start examples.
  • Document the threading guarantee after Thread-Unsafe Global _workspace_path_override Race #43: _workspace_path_override is protected by threading.Lock, so multi-threaded single-process deployment is supported; multi-process deployments note per-worker state for POST /api/set-workspace.
  • Consolidate WORKSPACE_PATH / CLI_CHATS_PATH / API path trust boundaries (validated API vs trusted-operator env vars).
  • Cover pywebview desktop mode and CLI export (no WSGI concerns).
  • Link from README (Deployment section, Configuration, Desktop App) and include DEPLOYMENT.md in the sdist via pyproject.toml.

Closes #48.

Test plan

  • Read DEPLOYMENT.md for accuracy against utils/workspace_path.py and app.py
  • Confirm gunicorn/waitress examples use app:create_app factory pattern
  • python -m unittest tests.test_workspace_path_thread_safety -v (regression for documented lock behavior)

Summary by CodeRabbit

  • Documentation
    • Added comprehensive deployment guide covering production server setups, threading behavior, workspace path configuration, desktop mode operation, and known system limitations.
    • Updated README.md with clearer deployment cross-references and refined workspace path override documentation.

Review Change Stack

@bradjin8 bradjin8 self-assigned this May 21, 2026
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 21, 2026 •
edited
Loading

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 81323c03-d414-450f-91af-7632ce9d375c

📥 Commits

Reviewing files that changed from the base of the PR and between 6074381 and 98756f9.

📒 Files selected for processing (3)
  • DEPLOYMENT.md
  • README.md
  • pyproject.toml
📝 Walkthrough

Walkthrough

A new DEPLOYMENT.md file documents production WSGI server configurations (gunicorn, waitress), development-server behavior, threading guarantees with serialized workspace-path override handling, multi-process caveats, workspace-path resolution order, trust boundaries for API vs environment overrides, desktop/CLI modes, and known limitations. The README is updated with three cross-references to the new guide at deployment, workspace-path, and desktop-mode sections. pyproject.toml includes the documentation in source distributions.

Changes

Deployment Documentation and Cross-references

Layer / File(s) Summary
New Deployment Documentation
DEPLOYMENT.md		 Complete deployment guide covering production WSGI server configurations (gunicorn/waitress), development server, threading guarantees via module-level lock serialization, multi-process workspace-override and reload caveats, workspace path resolution order and trust boundaries, desktop/pywebview and CLI export modes, and known limitations.
README Deployment Cross-references and Consolidation
README.md		 Three targeted updates: new "Deployment" subsection pointing to DEPLOYMENT.md for production/threading details; workspace path override paragraph rewritten to distinguish API-validated paths from trusted WORKSPACE_PATH env-var overrides; desktop app description augmented with threading link.
Source Distribution Packaging Update
pyproject.toml		 Added DEPLOYMENT.md to sdist [tool.hatch.build.targets.sdist].include list for distribution in source packages.

🎯 2 (Simple) | ⏱️ ~8 minutes

🐰 With gunicorn threads and env-var trust,
The workspace paths now documented—no fuss!
Desktop and CLI modes laid bare,
DEPLOYMENT.md shows operators care. ✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'docs: add deployment and threading safety guide' clearly and specifically describes the main change—adding documentation for deployment configurations and threading safety.
Linked Issues check ✅ Passed The PR implements all core requirements from issue #48: DEPLOYMENT.md covers WSGI configurations, threading constraints, concurrency models, quick-start examples, workspace path trust boundaries, and references to the thread-safety fix from PR #43.
Out of Scope Changes check ✅ Passed All changes are directly related to documenting deployment and threading safety as specified in issue #48; README and pyproject.toml updates are supporting changes that reference and distribute DEPLOYMENT.md.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/no-threading-deployment-safety-doc

Comment @coderabbitai help to get the list of available commands and usage tips.

@bradjin8 bradjin8 requested a review from clean6378-max-it May 21, 2026 12:49
@clean6378-max-it clean6378-max-it requested a review from wpak-ai May 21, 2026 20:32
@wpak-ai wpak-ai merged commit 731c1e1 into master May 21, 2026
16 checks passed
@wpak-ai wpak-ai deleted the fix/no-threading-deployment-safety-doc branch May 21, 2026 21:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@wpak-ai wpak-ai wpak-ai approved these changes

@clean6378-max-it clean6378-max-it clean6378-max-it approved these changes

Assignees

@bradjin8 bradjin8

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

No Threading/Deployment Safety Documentation

3 participants

@bradjin8 @wpak-ai @clean6378-max-it